<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>HOWTO use Jena to show RDF as frames</title>
  <link rev="made" href="mailto:ian.dickinson@hp.com" />
  <meta name="generator" content="Eclipse 3.0" />
  <meta name="author" content="Ian Dickinson" />
  <meta name="description" content="" />
  <meta name="keywords" content="" />
  <link href="../styles/doc.css" rel="stylesheet" type="text/css" />
  <style type="text/css">
  </style>
</head>

<body>

<h1 id="title">Presenting RDF as frames</h1>
<p>The origins of RDF as a representation language include <em>frame languages</em>,
  in which an object, or frame, was the main unit of structuring data. Frames have
  <em>slots</em>, for example a <code>Person</code> frame might have an <code>age</code>
  slot, a <code>height</code>slot etc.  RDF, however, has taken a step beyond frame
  languages by making <code>rdf:Property</code> a first class value, not an element
  of a frame or resource <em>per se</em>. In RDF, for example, an age property can
  be defined:
  <code>&lt;rdf:Property&nbsp;rdf:ID=&quot;age&quot;&gt;</code>, and then applied to
  any resource, including, but not limited to a <code>Person</code> resource.
</p>
<p>While this introduces an extra element of modelling flexibility in RDF, it is
  often the case that users want to treat some components in their models in
  a more structured way, similar to the original idea of frames. It is often
  assumed that <code>rdfs:domain</code> restricts a property to be used only
  on resources that are in the domain class. For example, a frequently asked
  question on the Jena support list is why the following is not an error:</p>
<pre>
  &lt;rdfs:Class rdf:ID=&quot;Person&quot; /&gt;
  &lt;rdfs:Class rdf:ID=&quot;Truck&quot; /&gt;
  &lt;rdf:Property rdf:ID=&quot;age&quot;&gt;
    &lt;rdfs:domain rdf:resource=&quot;Person&quot; /&gt;
  &lt;/rdf:Property&gt;

  &lt;Truck rdf:ID=&quot;truck1&quot;&gt;
    &lt;age&gt;2&lt;/a&gt;
  &lt;/Truck&gt;
</pre>
<p>Whereas many object-oriented or frame-oriented representations would regard it
  as an error that the <code>age</code> property was not being applied to a
  <code>Person</code>, RDF-based applications are simply entitled to infer
  that <code>truck1</code> is a (that is, has <code>rdf:type</code>)
  <code>Truck</code> as well as a <code>Person</code>.
  This is unlikely to be the case in any real-world domain, but it is a valid RDF
  inference.</p>
<p>A consequence of RDF's design is that it is not really possible to answer
  the commonly asked question &quot;Which properties can be applied to
  resources of class <em>C</em>?&quot;. Strictly speaking, the RDF answer is
  &quot;Any property&quot;. However, many developers have a legitimate requirement
  to present a composite view of classes and their associated properties, forming more
  a more succinct structuring of an ontology or schema. The purpose of this note
  is to explain the mechanisms built-in to Jena to support a frame-like view of
  resources, while remaining correct with respect to RDF (and OWL) semantics.
  </p>
  <h2 id="principles">Basic principles: the properties of a class</h2>
<p>Since any RDF property can be applied to any RDF resource, we require a
  definition of the properties of a given class that respects RDF semantics.
  Consider the following RDF fragment:</p>

<pre>
  &lt;rdfs:Class rdf:ID=&quot;Person&quot; /&gt;
  &lt;rdf:Property rdf:ID=&quot;age&quot; /&gt;

  &lt;Person rdf:ID=&quot;jane_doe&quot;&gt;
    &lt;age&gt;23&lt;/a&gt;
  &lt;/Person&gt;
</pre>

<p>Now consider that we add to this fragment that:</p>
<pre>
  &lt;rdf:Property rdf:about=&quot;age&quot;&gt;
    &lt;rdfs:domain rdf:resource=&quot;Person&quot; /&gt;
  &lt;/rdf:Property&gt;
</pre>

<p>This additional information about the domain of the <code>age</code>
  property does not add any new entailments to the model. Why? Because
  we already know that <code>jane_doe</code> is a Person.  So we can consider
  <code>age</code> to be one of the properties of <code>Person</code> type
  resources, because if we use the property as a predicate of that resource,
  it doesn't add any new <code>rdf:type</code> information about the resource.
  Conversely, if we know that some resource has an <code>age</code>, we don't
  learn any new information by declaring that it has <code>rdf:type Person</code>.
  In summary, for the purposes of this HOWTO
  we define the <em>properties of a class</em> as just those
  properties that don't entail any new type information when applied to
  resources that are already known to be of that class.
  </p>

<!--p>An alternative characterisation of the properties of a class, as defined in
  this HOWTO, is that they comprise the properties that characterise all
  members of the class. </p-->
<h2 id="classExpr">Sub-classes, and more complex class expressions</h2>
<p>Given these basic principles, now consider the following RDF fragment:</p>

<pre>
  &lt;rdfs:Class rdf:ID=&quot;LivingThing&quot; /&gt;

  &lt;rdfs:Class rdf:ID=&quot;Animal&quot;&gt;
    &lt;rdfs:subClassOf rdf:resource=&quot;#LivingThing&quot;&gt;
  &lt;/rdfs:Class&gt;

  &lt;rdfs:Class rdf:ID=&quot;Mammal&quot;&gt;
    &lt;rdfs:subClassOf rdf:resource=&quot;#Animal&quot;&gt;
  &lt;/rdfs:Class&gt;

  &lt;rdf:Property rdf:ID=&quot;hasSkeleton&quot;&gt;
    &lt;rdfs:domain rdf:resource=&quot;Animal&quot; /&gt;
  &lt;/rdf:Property&gt;
</pre>

<p>Is <code>hasSkeleton</code> one of the properties of <code>Animal</code>? Yes, because
  any resource of <code>rdf:type Animal</code> can have a <code>hasSkeleton</code> property
  (with value either true or false) without adding type information. Similarly,
  any resource that is a <code>Mammal</code> also has <code>rdf:type Animal</code>
  (by the sub-class relation), so <code>hasSkeleton</code> is a property of <code>Mammal</code>.
  However, <code>hasSkeleton</code> is <em>not</em> a property of <code>LivingThing</code>,
  since we don't automatically know that a living thing is an animal - it may
  be a plant. Stating that a given <code>LivingThing</code> has a <code>hasSkeleton</code>
  property, even if the value is false, would entail the additional
  <code>rdf:type</code> statement that the <code>LivingThing</code> is also
  an <code>Animal</code>.</p>

<p>For more complex class expressions in the domain, we look to see what simple
  domain constraints are entailed. For example, a domain constraint
  <code>A&nbsp;&cap;&nbsp;B</code> (i.e. &quot;A intersection B&quot;)
  for property <code>p</code>
  entails that both <code>p&nbsp;rdfs:domain&nbsp;A</code> and <code>p&nbsp;rdfs:domain&nbsp;B</code>
  are true. However, the properties of neither <code>A</code> nor <code>B</code>
  will include <code>p</code>. To see this, suppose we have a resource
  <code>x</code> that we already know is of type <code>A</code>, and a statement
  <code>x&nbsp;p&nbsp;y</code>. This entails <code>x&nbsp;rdf:type&nbsp;A</code>
  which we already know, but also <code>x&nbsp;rdf:type&nbsp;B</code>. So
  information is added, even if we know that <code>x</code> is an instance <code>A</code>,
  so <code>p</code> is not a property of <code>A</code>. The symmetrical argument
  holds for <code>p</code> not being a property of <code>B</code>.
</p><p>
  However, if the domain of <code>p</code> is
  <code>A&nbsp;&cup;&nbsp;B</code> (i.e. &quot;A union B&quot;),
  then both <code>A</code> and <code>B</code>
  will have <code>p</code> as a property, since an occurrence of, say
  <code>x&nbsp;p&nbsp;y</code> does not allow us to conclude that either
  <code>x&nbsp;rdf:type&nbsp;A</code> or <code>x&nbsp;rdf:type&nbsp;B</code>.</p>

<h2 id="propHier">Property hierarchies</h2>
<p>Since sub-properties inherit the domain constraints of their parent
  property, the properties of a class will include the closure over the sub-property
  hierarchy. Extending the previous example, the properties of <code>Animal</code>
  and <code>Mammal</code> include both <code>hasSkeleton</code> and <code>hasEndoSkeleton</code>:</p>
<pre>
  &lt;rdf:Property rdf:ID=&quot;hasSkeleton&quot;&gt;
    &lt;rdfs:domain rdf:resource=&quot;Animal&quot; /&gt;
  &lt;/rdf:Property&gt;

  &lt;rdf:Property rdf:ID=&quot;hasEndoSkeleton&quot;&gt;
    &lt;rdfs:subPropertyOf rdf:resource=&quot;#hasSkeleton&quot; /&gt;
  &lt;/rdf:Property&gt;
</pre>

<p>In general, there may be many different ways of deducing simple domain constraints
  from the axioms asserted in the ontology. Whether or not all of these possible
  deductions are present in any given RDF model depends on the power and completeness
  of the reasoner bound to that model.</p>

<h2 id="globalProps">Global properties</h2>
<p>Under the principled definition that we propose here, properties which do not
  express a domain value are <em>global</em>, in the sense that they can apply
  to any resource. They do not, by definition, entail any new type information
  about the individuals they are applied to. Put another way, the domain of a
  property, if unspecified, is either <code>rdfs:Resource</code> or <code>owl:Thing</code>,
  depending on the ontology language. These are simply the types that all resources
  have by default. Therefore, every class has all of the global properties as one
  of the properties of the class.</p>
<p>A commonly used idiom in some OWL ontologies is to use <em>Restrictions</em>
  to create an association between a class and the properties of instances
  of that class. For example, the following fragment shows that all instances
  of <code>Person</code> should have a <code>familyName</code> property:</p>

<pre>
  &lt;owl:Class rdf:ID=&quot;Person&quot;&gt;
    &lt;rdfs:subClassOf&gt;
      &lt;owl:Restriction&gt;
        &lt;owl:onProperty rdf:resource=&quot;#familyName&quot; /&gt;
        &lt;owl:minCardinality rdf:datatype=&quot;&amp;xsd;int&quot;&gt;1&lt;/owl:minCardinality&gt;
      &lt;/owl:Restriction&gt;
    &lt;/rdfs:subClassOf&gt;
  &lt;/owl:Class&gt;
</pre>

<p>This approach shows the intent of the ontology designer that <code>Person</code>
  instances have <code>familyName</code> properties.
  We do regard <code>familyName</code> as one of
  the <em>properties of</em> <code>Person</code>, but only because of the
  global properties principle. Unless a domain constraint is also specified for
  <code>familyName</code>, it will appear as one of the properties of classes
  other than <code>Person</code>.
  <strong>Note that this is a behaviour change from versions of
    Jena prior to release 2.2</strong>. Prior to this release, Jena used a
    heuristic method to attempt to associate restriction properties with the
    classes sub-classing that restriction. Since there were problems with
    precisely defining the heuristic, and ensuring correct behaviour (especially
    with inference models), we have dropped the use of this heuristic from Jena
    2.2 onwards.
  </p>

<h2 id="java_api">The Java API</h2>
<p>Support for frame-like views of classes and properties is provided through
  the <a href="../ontology/index.html">ontology API</a>. The following methods
  are used to access the properties of a class, and the converse for
  properties:</p>
<pre>
  OntClass.<a href="../javadoc/com/hp/hpl/jena/ontology/OntClass.html#listDeclaredProperties()">listDeclaredProperties</a>();
  OntClass.<a href="../javadoc/com/hp/hpl/jena/ontology/OntClass.html#listDeclaredProperties(boolean)">listDeclaredProperties</a>( boolean direct );
  OntClass.<a href="../javadoc/com/hp/hpl/jena/ontology/OntClass.html#hasDeclaredProperty(Property,boolean)">hasDeclaredProperty</a>( Property prop, boolean direct );
  OntProperty.<a href="../javadoc/com/hp/hpl/jena/ontology/OntProperty.html#listDeclaringClasses()">listDeclaringClasses</a>();
  OntProperty.<a href="../javadoc/com/hp/hpl/jena/ontology/OntClass.html#listDeclaringClasses(boolean)">listDeclaringClasses</a>( boolean direct );
</pre>

<p>All of the above API methods return a Jena
  <a href="../javadoc/com/hp/hpl/jena/util/iterator/ExtendedIterator.html"><code>ExtendedIterator</code></a>. </p>

<p><strong>Note a change from the Jena 2.1 interface:</strong> the
  optional Boolean parameter on <code>listDeclaredProperties</code> has
  changed name from <code>all</code> (Jena 2.1 and earlier) to
  <code>direct</code> (Jena 2.2 and later). The meaning of the parameter
  has also changed: <code>all</code> was intended to simulate some reasoning
  steps in the absence of a reasoner, whereas <code>direct</code> is used
  to restrict the associations to only the local associations. See
  more on <a href="../ontology/index.html#direct_relationships">direct associations</a>.</p>

<p>A further difference from Jena 2.1 is that the models that are constructed without
  reasoners perform only very limited simulation of the inference closure of the
  model. Users
  who wish the declared properties to include entailments will need to construct
  their models with one of the built-in or external reasoners. The difference is
  illustrated by the following code fragment:</p>
<pre>
  &lt;rdfs:Class rdf:ID=&quot;A&quot; /&gt;
  &lt;rdfs:Property rdf:ID=&quot;p&quot;&gt;
    &lt;rdfs:domain rdf:resource=&quot;#A&quot; /&gt;
  &lt;/rdfs:Property&gt;
  &lt;rdfs:Property rdf:ID=&quot;q&quot;&gt;
    &lt;rdfs:subPropertyOf rdf:resource=&quot;#p&quot; /&gt;
  &lt;/rdfs:Property&gt;

  OntModel mNoInf = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM );
  OntClass a0 = mNoInf.getOntClass( NS + &quot;A&quot; );
  Iterator i0 = a0.listDeclaredProperties();

  OntModel mInf = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM_RULE_INF );
  OntClass a1 = mInf.getOntClass( NS + &quot;A&quot; );
  Iterator i1 = a1.listDeclaredProperties();
</pre>
<p>Iterator <code>i1</code> will return <code>p</code> and <code>q</code>, while
  <code>i0</code> will return only <code>p</code>.</p>

<h2 id="changes_from_2_1">Summary of changes from Jena 2.2-beta-2 and older</h2>
<p>For users updating code that uses <code>listDeclaredProperties</code> from
  versions of Jena prior to 2.2-final, the following changes should be noted:</p>
<ul>
  <li>Global properties<br />
    <code>listDeclaredProperties</code> will treat properties with no specified
    domain as global, and regard them as properties of all classes. The use
    of the <code>direct</code> flag can hide global properties from non-root
    classes.</li>
  <li>Restriction properties<br />
    <code>listDeclaredProperties</code> no longer heuristically
    returns properties associated
      with a class via the <code>owl:onProperty</code> predicate of a restriction.
      </li>
  <li>Limited simulated inference<br />
    The old version of <code>listDeclaredProperties</code> attempted to simulate
    the entailed associations between classes and properties. Users are now advised
    to attach a reasoner to their models to do this.</li>
  <li>Change in parameter semantics<br />
    The old version of <code>listDeclaredProperties(boolean&nbsp;all)</code> took one parameter,
    a Boolean flag to indicate whether additional declared (implied) properties should
    be listed. Since this is now covered by the use, or otherwise, of a reasoner
    attached to the model, the new method signature is
    <code>listDeclaredProperties(boolean&nbsp;direct)</code>, where calling the
    method with <code>direct&nbsp;=&nbsp;true</code> will compress the returned
    results to use only the <a href="../ontology/index.html#direct_relationships">direct</a>
    associations.</li>
</ul>

  <hr />

<p><small>CVS $Id: rdf-frames.html,v 1.6 2005/04/19 12:31:02 andy_seaborne Exp $</small></p>
</body>
</html>
